% !TEX root = TMV_Documentation.tex

\section{Vectors}
\index{Vector}
\label{Vector}

The \tt{Vector} class in TMV represents a mathematical vector\footnote{Don't confuse it with
the standard template library's \tt{vector} class.
Our \tt{Vector} class name is capitalized, while the STL \tt{vector} is not.
If this is not enough of a difference for you, and you are using both extensively in your code,
we recommend keeping the full \tt{tmv::Vector} designation for ours and \tt{std::vector}
for theirs to distinguish them.  Or you might want to \tt{typedef tmv::Vector} to some other name that you prefer.}.

The \tt{Vector} class is templated with two template arguments.  The first one is the type of
the data, which we call \tt{T} below.
The second template argument is an integer that defines some attributes about the \tt{Vector}.
The only valid attributes for a \tt{Vector}
are \tt{tmv::CStyle} and \tt{tmv::FortranStyle}, which specify how the element
access is performed.  (We'll have more attribute options later for
matrices.)  We call the attribute parameter \tt{A} below.  If it is omitted, \tt{CStyle} is assumed.  

With C-style indexing, the first element of a \tt{Vector} of length \tt{N} is 
\tt{v(0)} and the last is \tt{v(N-1)}.  Also, methods that take range arguments
use the common C convention of ``one-past-the-end'' for the last element;
so \tt{v.subVector(0,3)} returns a 3-element vector, not 4.

With Fortran-style indexing, the first element of the vector is \tt{v(1)} and the 
last is \tt{v(N)}.  Ranges are specified by the first and last elements, so the same
subvector as above would now be accessed using \tt{v.subVector(1,3)} to return
the first three elements.

All views of a \tt{Vector} keep the same indexing style as the original unless you
explicitly change it with a cast.  You can cast a \tt{VectorView<T,CStyle>} as
a \tt{VectorView<T,FortranStyle>} and vice versa.  Likewise for
\tt{ConstVectorView}.  

\subsection{Constructors}
\index{Vector!Constructors}
\label{Vector_Constructors}

Remember, the \tt{A} attributes parameter listed here is optional.  If it is omitted, \tt{CStyle} is assumed.

\begin{itemize}

\item 
\begin{tmvcode}
tmv::Vector<T,A> v()
\end{tmvcode}
Makes a \tt{Vector} of zero size.  You would normally use the \tt{resize} function later to 
change the size to some useful value.

\item 
\begin{tmvcode}
tmv::Vector<T,A> v(int n)
\end{tmvcode}
Makes a \tt{Vector} of size \tt{n} with {\em uninitialized} values.
If extra debugging is turned on (with the compiler flag \tt{-DTMV\_EXTRA\_DEBUG}), then the values are in fact initialized to 888.  This should help you notice when you have neglected to initialize the \tt{Vector} correctly.

\item
\begin{tmvcode}
tmv::Vector<T,A> v(int n, T x)
\end{tmvcode}
Makes a \tt{Vector} of size \tt{n} with all values equal to \tt{x}

\item
\begin{tmvcode}
tmv::Vector<T,A> v = tmv::BasisVector<T,A>(int n, int i)
\end{tmvcode}
Makes a \tt{Vector} whose elements are all \tt{0}, except \tt{v(i) = 1}.
Note the \tt{BasisVector} also has the \tt{A} template argument to 
indicate which element is meant by \tt{v(i)}.  Again, if it is omitted,
\tt{CStyle} is assumed.

\item
\begin{tmvcode}
tmv::Vector<T,A> v1(const tmv::Vector<T2,A2>& v2)
v1 = v2
\end{tmvcode}
Copy the \tt{Vector v2}, which may be of any type \tt{T2} so long
as values of type \tt{T2} are convertible into type \tt{T}.
The assignment operator has the same flexibility.

\item
\begin{tmvcode}
tmv::VectorView<T,A> v = 
      tmv::VectorViewOf(T* vv, int n, int step=1)
tmv::ConstVectorView<T,A> v = 
      tmv::VectorViewOf(const T* vv, int n, int step=1)
\end{tmvcode}
\index{Vector!View of raw memory}
Makes a \tt{VectorView} (see \S\ref{Vector_Views} below) which refers to the exact
elements of \tt{vv}, not copying them to new storage.  The parameter \tt{n}
is the number of values to include in the view.
The optional \tt{step} parameter allows a non-unit spacing between 
successive vector elements in memory. 

\end{itemize}

\subsection{Access}
\index{Vector!Access methods}
\label{Vector_Access}

\begin{itemize}
\item
\begin{tmvcode}
int v.size() const
\end{tmvcode}
\index{Vector!Methods!size}
Returns the size (length) of \tt{v}.

\item
\begin{tmvcode}
T v[int i] const
T v(int i) const
Vector<T>::reference v[int i]
Vector<T>::reference v(int i)
T v.cref(int i) const
Vector<T>::reference v.ref(int i)
\end{tmvcode}
\index{Vector!Methods!operator()}
\index{Vector!Methods!operator[]}
\index{Vector!Methods!cref}
\index{Vector!Methods!ref}
The \tt{[]} and \tt{()} forms are equivalent.  Each returns the \tt{i}-th element of \tt{v}.  
With \tt{A = CStyle}, the first 
element is \tt{v(0)}, and the last element is \tt{v(n-1)}.
With \tt{A = FortranStyle}, they are \tt{v(1)} and \tt{v(n)}.

If \tt{v} is a 
\tt{const Vector} or a \tt{ConstVectorView},
then the return type is just the value, not a reference.

If \tt{v} is a 
non-\tt{const Vector}, then the return type is a normal reference, \tt{T\&}.

If \tt{v} is a \tt{VectorView}, then the return type is an object, which is
an lvalue (i.e. it is assignable), but which may not be \tt{T\&}.
Specifically, it has the type \tt{VectorView<T>::reference}.
For a real-typed \tt{VectorView}, it is just \tt{T\&}.  But for a
complex-typed \tt{VectorView}, the return type is an object that keeps track of the
possibility of a conjugation.

The main difference between the operator forms and \tt{cref} or \tt{ref} is that the latter versions do not
check for the validity of the parameter \tt{i}, even when compiling with debugging turned on.
Also, \tt{cref} and \tt{ref} always use \tt{CStyle} indexing.


\item
\begin{tmvcode}
Vector<T>::iterator v.begin()
Vector<T>::iterator v.end()
Vector<T>::const_iterator v.begin() const
Vector<T>::const_iterator v.end() const
Vector<T>::reverse_iterator v.rbegin()
Vector<T>::reverse_iterator v.rend()
Vector<T>::const_reverse_iterator v.rbegin() const
Vector<T>::const_reverse_iterator v.rend() const
\end{tmvcode}
\index{Vector!Iterators}
\index{Vector!Methods!begin}
\index{Vector!Methods!end}
\index{Vector!Methods!rbegin}
\index{Vector!Methods!rend}
These provide iterator-style access into a \tt{Vector}.  The iterators all conform to the standard library's random-access iterator requirements, so you can use these in any standard library routine that takes iterators.  For example, to copy from a \tt{std::vector v1} to a \tt{tmv::Vector v2}, you could write:
\begin{tmvcode}
std::copy(v1.begin(),v1.end(),v2.begin());
\end{tmvcode}
Note: If \tt{v} is a \tt{VectorView},
the iterator types are slightly different from the \tt{Vector} iterators, 
so you should declare them as \tt{VectorView<T>::iterator},
etc. instead.

\item
\begin{tmvcode}
T* v.ptr()
const T* v.cptr() const
\end{tmvcode}
\index{Vector!Methods!ptr}
\index{Vector!Methods!cptr}
These methods return the pointer to the memory location of the first element of the vector.  These aren't usually necessary, but sometimes they can be useful for writing optimized code or for meshing with other libraries that need the direct memory access.

\item
\begin{tmvcode}
int v.step() const
\end{tmvcode}
\index{Vector!Methods!step}
This returns the step size in memory between elements in the vector.  It is usually only required if you are accessing the memory directly with \tt{v.ptr()}.

\item
\begin{tmvcode}
bool v.isconj() const
\end{tmvcode}
\index{Vector!Methods!isconj}
This returns whether or not the elements of the vector are actually the conjugate of the values in memory.  Again, this is usually only required if you are accessing the memory directly.

\end{itemize}

\subsection{Initialization}
\index{Vector!Initialization}
\label{Vector_Initialization}

There are a number of ways to initialize the elements of a \tt{Vector}.
The most straightforward way is to simply set each element individually:
\begin{tmvcode}
for(int i=0; i<N; ++i) {
    v[i] = 5+i; // or whatever
}
\end{tmvcode}
But this is often inconvenient, especially if you want to assign a particular list of 
values that does not lend itself to being put in a \tt{for} loop.  Of course you can assign
each element one line at a time, but that can be a bit unwieldy.  So another 
way is to use a C array initializer, and then copy the values into the vector.  For example:
\begin{tmvcode}
double var[5] = { 1.2, 3.2, -9.2, -1, 3.3 };
tmv::Vector<double> v(5);
std::copy(var,var+5,v.begin());
\end{tmvcode}
This works, but it seems a bit inefficient to use a temporary variable.
The better way to do this with TMV is to initialize the \tt{Vector} with the \tt{<<} operator, analogous to the \tt{<<} syntax for \tt{std::ostream}.
The idea is that we are sending information into the \tt{Vector}.  
After the initial \tt{<<}, the elements are separated by either more \tt{<<}'s or commas.\footnote{
I tend to prefer the commas, but using the \tt{<<} operator between each element would
match the analogy with \tt{ostream} better.}
\begin{tmvcode}
tmv::Vector<double> v(5);
v << 1.2, 3.2, -9.2, -1, 3.3;
v << 1.2 << 3.2 << -9.2 << -1 << 3.3;
\end{tmvcode}
\index{Vector!List initialization}
There must be precisely as many values as there are elements in the \tt{Vector},
or a \tt{tmv::ReadError} will be thrown, although unlike most \tt{ReadError}s this is only 
checked when TMV is in debugging mode (i.e. not compiled with \tt{-DNDEBUG} or \tt{-DTMV_NDEBUG}).
\index{Exceptions!ReadError}

One advantage of this method for initialization is that the values do not need to be simple numbers.
Normally the elements in a list initializer need to be numerical literals, or at least to be 
computable at compile time.
With the above syntax, the elements can be variables, 
or even values returned from functions.  Anything that is convertible
into the element type of the \tt{Vector} will work.

Also, \tt{v} can be a \tt{VectorView}, not just a \tt{Vector}, so you can use this method to 
initialize just part of a \tt{Vector}, or a single row or column of a \tt{Matrix}, etc.

\subsection{Resizing}
\index{Vector!Resizing}
\label{Vector_Resize}

It is possible to change the size of a vector after it has been created using the method \tt{resize}:

\begin{tmvcode}
v.resize(int newsize);
\end{tmvcode}
\index{Vector!Methods!resize}
This reallocates memory for the new size with {\em uninitialized} values.  
There are no correlates to the other constructors, so after a resize, the 
values should be set directly in some fashion.

Note that there is no automatic resizing if assigning a result that is a different size. 
For example, the code:
\begin{tmvcode}
tmv::Vector<double> v(10);
tmv::Vector<double> w(20);
// w = ...
v = 5. * w;  // Error: sizes don't match.
\end{tmvcode}
will throw a \tt{tmv::FailedAssert} exception (c.f. \S\ref{FailedAssert}) (Or if compiled with 
\tt{-DNDEBUG} or \tt{-DTMV\_NDEBUG} to skip TMV's asserts, then it will probably produce a segmentation fault.),
rather than resizing \tt{v} to a size of 20.  

The reason for this is that such code is more often the result of a bug, rather than intent.
So if this code is what you intend, you should write the following:
\begin{tmvcode}
v.resize(20);
v = 5. * w;  // OK: sizes match now.
\end{tmvcode}

Also, only actual \tt{Vector}s can be resized, not the views that we will discuss in the next section.

\subsection{Views}
\index{Vector!VectorView}
\index{Vector!Views}
\label{Vector_Views}

A \tt{VectorView<T>} object refers to the elements of some other object, such as a regular
\tt{Vector<T>} or \tt{Matrix<T>},
so that altering the elements in the view alters the
corresponding elements in the original object.  A \tt{VectorView}
can have non-unit
steps between elements (for example, a view of a column of a row-major
matrix).  It can also be a conjugation of the original
elements, so that
\begin{tmvcode}
tmv::VectorView<double> cv = v.conjugate();
cv(3) = z;
\end{tmvcode}
would actually set the original element, \tt{v(3)} to \tt{conj(z)}. 

Also, we have to 
keep track of whether we are allowed to alter the original values or
just look at them.  
Since we want to be able to pass these views around, it turns out that
the usual \tt{const}-ing doesn't work the way you would want.
Thus, there are two objects that are views of a
\tt{Vector}:
\tt{ConstVectorView} and \tt{VectorView}.  
The first is only allowed to view,
not modify, the original elements.  The second is allowed to modify them.
This distinction is akin to the \tt{const\_iterator} and \tt{iterator} types in the
standard template library.

The following methods return views to portions of a \tt{Vector}.
If \tt{v} is either a (non-\tt{const}) \tt{Vector}
or a \tt{VectorView}, then a \tt{VectorView} is returned.
If \tt{v} is a \tt{const Vector} or a \tt{ConstVectorView},
then a \tt{ConstVectorView} is returned.  

\begin{itemize}
\item
\begin{tmvcode}
v.subVector(int i1, int i2, int istep=1)
\end{tmvcode}
\index{Vector!Methods!subVector}
This returns a view to a subset of the original vector.
\tt{i1} is the first element in the subvector.
\tt{i2} is either ``one past the end'' (C-style) or the last element
(Fortran-style) of the subvector according to the attribute parameter of \tt{v}.
\tt{istep} is an optional step size.
Thus, if you have a \tt{Vector v} of length 10, and you want to
multiply the first 3 elements by 2, with C-style indexing, you could write:
\begin{tmvcode}
v.subVector(0,3) *= 2.;
\end{tmvcode}
To set all the even elements to 0, you could write:
\begin{tmvcode}
v.subVector(0,10,2).setZero();
\end{tmvcode}
And then to output the last 4 elements of \tt{v}, you could write:
\begin{tmvcode}
std::cout << v.subVector(6,10);
\end{tmvcode}

For Fortran-style indexing, the same steps would be accomplished by:
\begin{tmvcode}
v.subVector(1,3) *= 2.;
v.subVector(1,9,2).setZero();
std::cout << v.subVector(7,10);
\end{tmvcode}

\item
\begin{tmvcode}
v.reverse()
\end{tmvcode}
\index{Vector!Methods!reverse}
This returns a view whose elements are the same as \tt{v},
but in the reverse order

\item
\begin{tmvcode}
v.conjugate()
\end{tmvcode}
\index{Vector!Methods!conjugate}
This returns the conjugate of a \tt{Vector} as a view, so it still points
to the same physical elements, but modifying this will set the 
actual elements in memory to the conjugate of what you set.  Likewise,
accessing an element will return the conjugate of the value in memory.

\item
\begin{tmvcode}
v.view()
\end{tmvcode}
\index{Vector!Methods!view}
Returns a view of a \tt{Vector}.  This seems at first like a silly function to have, but
if you write a function that takes a mutable \tt{Vector} argument, and you want to
be able to pass it views in addition to regular \tt{Vector}s, it is easier to write the 
function once with a \tt{VectorView} parameter.  Then you only need a second 
function with a \tt{Vector} parameter, which calls the first function
using \tt{v.view()} as the argument:
\begin{tmvcode}
double foo(tmv::VectorView<double> v)
{ ... [modifies v] ... }
double foo(tmv::Vector<double>& v)
{ return foo(v.view()); }
\end{tmvcode}

\item
\begin{tmvcode}
v.cView()
v.fView()
\end{tmvcode}
\index{Vector!Methods!cView}
\index{Vector!Methods!fView}
Like \tt{view()} but forces the result to have C- or Fortran-style indexing respectively.

\item
\begin{tmvcode}
v.realPart()
v.imagPart()
\end{tmvcode}
\index{Vector!Methods!realPart}
\index{Vector!Methods!imagPart}
These return views to the real and imaginary parts of a complex \tt{Vector}.
Note the return type is a real view in each case:
\begin{tmvcode}
tmv::Vector<std::complex<double> > v(10,std::complex<double>(1,4));
tmv::VectorView<double> vr = v.realPart();
tmv::VectorView<double> vi = v.imagPart();
\end{tmvcode}

\item
\begin{tmvcode}
tmv::VectorView<RT> v.flatten()
\end{tmvcode}
\index{Vector!Methods!flatten}
This returns a real view to the real and imaginary elements of a complex \tt{Vector}. 
The vector \tt{v} is required to have unit step.  The returned view has twice the 
length of \tt{v} and also has unit step.

\end{itemize}

\subsection{Functions of a vector }
\index{Vector!Functions of}
\label{Vector_Functions}

Functions that do not modify the \tt{Vector} 
can take as their argument either a regular \tt{Vector} or either
kind of \tt{View}.  You may even pass it an arithmetic expression that is
assignable to a \tt{Vector}, and TMV will automatically create the 
necessary temporary storage for the result.  (e.g. \tt{Norm(v1-5*v2)}.)

Functions that modify the \tt{Vector} are only defined for 
\tt{Vector} and \tt{VectorView}.

Some functions are invalid if T is \tt{int} or \tt{complex<int>} because they require 
a \tt{sqrt}.  If called, these functions typically return \tt{0} if there is a return value.
And if the library is compiled with debugging on (\tt{DEBUG=true} in the scons installation),
then they will throw a \tt{FailedAssert} exception.  The descriptions for such functions
will mention if they are invalid for integer types.

\subsubsection{Non-modifying functions}

Each of the following functions can be written in two ways, either as a method or a function.
For example, the expressions:
\begin{tmvcode}
double normv = v.norm();
double normv = Norm(v);
\end{tmvcode}
are equivalent.
Also, several of the functions below have multiple equivalent names.  For example,
\tt{norm1} and \tt{sumAbsElements} are equivalent, so you can use whichever one is
clearer to you in your situation.  And just to remind you, \tt{RT} refers to the 
real type associated with \tt{T}.  So if \tt{T} is either \tt{double} or \tt{complex<double>},
\tt{RT} would be \tt{double}.

\begin{itemize}

\item
\begin{tmvcode}
RT v.norm1() const
RT Norm1(v)
RT v.sumAbsElements() const
RT SumAbsElements(v)
\end{tmvcode}
\index{Vector!Methods!norm1}
\index{Vector!Functions of!Norm1}
\index{Vector!Methods!sumAbsElements}
\index{Vector!Functions of!SumAbsElements}
The 1-norm of \tt{v}: $||v||_1 = \sum_i |v(i)|$.  

Invalid for \tt{T = complex<int>}.

\item
\begin{tmvcode}
RT v.norm2() const
RT Norm2(v)
RT v.norm() const
RT Norm(v)
\end{tmvcode}
\index{Vector!Methods!norm}
\index{Vector!Functions of!Norm}
\index{Vector!Methods!norm2}
\index{Vector!Functions of!Norm2}
The 2-norm of \tt{v}: $||v||_2 = (\sum_i |v(i)|^2)^{1/2}$.
This is the most common meaning for the norm of a vector, so we
define the \tt{norm} function to be the same as \tt{norm2}.  

Invalid for \tt{T = int} or \tt{complex<int>}.

\item
\begin{tmvcode}
RT v.normSq(const RT scale=1) const
RT NormSq(v)
\end{tmvcode}
\index{Vector!Methods!normSq}
\index{Vector!Functions of!NormSq}
The square of the 2-norm of \tt{v}: $(||v||_2)^2 = \sum_i |v(i)|^2$.
In the method version of this function, you may provide an optional scale factor,
in which case the return value is equal to NormSq(scale*v) instead, 
which can help avoid underflow or overflow problems.

\item
\begin{tmvcode}
RT v.normInf() const
RT NormInf(v)
RT v.maxAbsElement() const
RT MaxAbsElement(v)
\end{tmvcode}
\index{Vector!Methods!normInf}
\index{Vector!Functions of!NormInf}
\index{Vector!Methods!maxAbsElement}
\index{Vector!Functions of!MaxAbsElement}
The infinity-norm of \tt{v}: $||v||_\infty = \max_i |v(i)|$.  

Invalid for \tt{T = complex<int>}.

\item
\begin{tmvcode}
T v.sumElements() const
T SumElements(v)
\end{tmvcode}
\index{Vector!Methods!sumElements}
\index{Vector!Functions of!SumElements}
The sum of the elements of \tt{v} $= \sum_i v(i)$.

\item
\begin{tmvcode}
RT v.sumAbs2Elements() const
RT SumAbs2Elements(v)
\end{tmvcode}
\index{Vector!Methods!sumAbs2Elements}
\index{Vector!Functions of!SumAbs2Elements}
The sum of the ``\tt{Abs2}'' values of the elements of \tt{v}: $\sum_i |real(v(i))| + |imag(v(i))|$.
This is faster than the version using real absolute values for
complex vectors and is often just as useful, depending on your purpose.  Also this version
is valid for \tt{T = complex<int>}, while the normal version is not.

\item
\begin{tmvcode}
T v.maxElement(int* i=0) const
T MaxElement(v)
T v.minElement(int* i=0) const
T MinElement(v)
\end{tmvcode}
\index{Vector!Methods!maxElement}
\index{Vector!Functions of!MaxElement}
\index{Vector!Methods!minElement}
\index{Vector!Functions of!MinElement}
The maximum/minimum element.  For complex values, there is no way to define a 
max or min element, so just the real component of each element is used.
The \tt{i} argument is available in the method versions of these function, and it is optional.
If it is present (and not 0), then \tt{*i} is set to the 
index of the max/min element returned.

\item
\begin{tmvcode}
RT v.maxAbsElement(int* i=0) const
RT MaxAbsElement(v)
RT v.minAbsElement(int* i=0) const
RT MinAbsElement(v)
\end{tmvcode}
\index{Vector!Methods!maxAbsElement}
\index{Vector!Functions of!MaxAbsElement}
\index{Vector!Methods!minAbsElement}
\index{Vector!Functions of!MinAbsElement}
The maximum/minimum element by absolute value.  $max_i |v(i)|$ or $min_i |v(i)|$.
The \tt{i} argument is available in the method versions of these function, and it is optional.
If it is present (and not 0), then \tt{*i} is set to the 
index of the max/min element returned.  

Invalid for \tt{T = complex<int>}.

\item
\begin{tmvcode}
RT v.maxAbs2Element(int* i=0) const
RT MaxAbs2Element(v)
RT v.minAbs2Element(int* i=0) const
RT MinAbs2Element(v)
\end{tmvcode}
\index{Vector!Methods!maxAbs2Element}
\index{Vector!Functions of!MaxAbs2Element}
\index{Vector!Methods!minAbs2Element}
\index{Vector!Functions of!MinAbs2Element}
The same as the above functions, but using
$|real(v(i))| + |imag(v(i))|$ instead of the normal absolute value if \tt{T} is complex.  
This is faster than doing
the normal absolute value, and for many purposes (such as finding a suitably large value
with which to scale a vector), it is just as useful.  Also these functions are
valid for \tt{T = complex<int>}, while the normal versions are not.

\end{itemize}


\subsubsection{Modifying functions}

The following functions are methods of both \tt{Vector} and \tt{VectorView},
and they work the same way in the two cases, although there may be speed differences
between them.  
All of these are usually written on a line by themselves.  However, they do
return the (modified) \tt{Vector}, so you can string them together if you want.
For example:
\begin{tmvcode}
v.clip(1.e-10).conjugateSelf().reverseSelf();
\end{tmvcode}
\index{Vector!Functions of!Norm}
would first clip the elements at \tt{1.e-10}, then conjugate each element, then finally reverse the
order of the elements.  (This would probably not be considered 
very good programming style, however.)
Likewise, the expression:
\begin{tmvcode}
foo(v.clip(1.e-10));
\end{tmvcode}
which would first clip the elements at \tt{1.e-10},
then pass the resulting \tt{Vector} to the function \tt{foo}.  

\begin{itemize}

\item
\begin{tmvcode}
v.setZero();
\end{tmvcode}
\index{Vector!Methods!setZero}
Clear the \tt{Vector v}.  i.e. Set each element to 0.

\item
\begin{tmvcode}
v.setAllTo(T x);
\end{tmvcode}
\index{Vector!Methods!setAllTo}
Set each element to the value \tt{x}.

\item
\begin{tmvcode}
v.addToAll(T x)
\end{tmvcode}
\index{Vector!Methods!addToAll}
Add the value \tt{x} to each element.

\item
\begin{tmvcode}
v.clip(RT thresh)
\end{tmvcode}
\index{Vector!Methods!clip}
Set each element whose absolute value is less than \tt{thresh} equal to 0.
Note that \tt{thresh} should be a real value even for complex valued
\tt{Vector}s.  

Invalid for \tt{T = complex<int>}.

\item 
\begin{tmvcode}
v.conjugateSelf()
\end{tmvcode}
\index{Vector!Methods!conjugateSelf}
Change each element into its complex conjugate.  
Note the difference between this and \tt{v.conjugate()}, 
which returns a \underline{view} to a conjugated version of \tt{v} without
actually changing the underlying data.  This function, \tt{v.conjugateSelf()},
does change the underlying data.

\item
\begin{tmvcode}
v.reverseSelf()
\end{tmvcode}
\index{Vector!Methods!reverseSelf}
Reverse the order of the elements.  Note the difference between this and 
\tt{v.reverse()} which returns a \underline{view} to the elements in 
reversed order.

\item
\begin{tmvcode}
v.makeBasis(int i)
\end{tmvcode}
\index{Vector!Methods!makeBasis}
Set all elements to 0, except for \tt{v(i)} = 1.

\item
\begin{tmvcode}
v.swap(int i1, int i2)
\end{tmvcode}
\index{Vector!Methods!swap}
Swap elements \tt{v(i1)} and \tt{v(i2)}.

\item
\begin{tmvcode}
v.sort(Permutation& p, tmv::ADType ad=tmv::Ascend, 
      tmv::CompType comp=tmv::RealComp)
v.sort(tmv::ADType ad=tmv::Ascend, 
      tmv::CompType comp=tmv::RealComp)
\end{tmvcode}
\index{Vector!Methods!sort}
\index{Permutation!Vector sort}
Sorts the vector \tt{v}, optionally returning the corresponding permutation in \tt{p}.
If you do not care about the permutation, the second form is slightly more efficient.

The returned permutation is such that if you have stored the initial vector as
\tt{v\_i}, then you can reproduce the sort operation with: \tt{v = p * v\_i}.
More commonly, the permutation is used to effect the same permutation on a 
different vector or matrix.

The next parameter, \tt{ad}, determines whether the sorted \tt{Vector} 
will have its elements in ascending or descending order.  The possible values
are \tt{Ascend} and \tt{Descend}.  The default if omitted is to sort
in ascending order.

The final parameter, \tt{comp}, determines what component of the
elements to use for the sorting.  This is especially relevant if T is complex, 
since complex values are not intrinsically sortable.
The possible values are
\tt{RealComp}, \tt{AbsComp},
\tt{ImagComp}, and \tt{ArgComp}.
Only the first two make sense for non-complex vectors.  The default if
omitted is to sort the real values of the elements.  

\tt{AbsComp} and \tt{ArgComp} are invalid for \tt{T = complex<int>}.

\item
\begin{tmvcode}
Swap(v1,v2)
\end{tmvcode}
\index{Vector!Functions of!Swap}
Swap the corresponding elements of \tt{v1} and \tt{v2}.  Note that if v1 and/or v2 are
views, this does physically
swap the data elements, not just some pointers to the data.  This is the intuitive 
meaning of a statement like
\begin{tmvcode}
Swap(m.row(4),m.row(5));
\end{tmvcode}
Clearly what is desired by that is to swap the actual values, and this is what we actually do.

However, if \tt{v1} and \tt{v2} are both \tt{tmv::Vector} objects, rather than views, then the 
swap efficiently swaps the pointers to the data, and so takes $O(1)$ time, rather than
$O(N)$.

\end{itemize}

\subsection{Arithmetic}
\index{Vector!Arithmetic}
\label{Vector_Arithmetic}

\subsubsection{Operators}

All the usual operators work the way you would expect for \tt{Vector}s.  For shorthand in the 
following list, I use \tt{x} for a scalar of type \tt{T} or \tt{RT}, and
\tt{v} for a \tt{Vector}.  When there are two \tt{Vector}s
listed, they may either be both of the same type \tt{T}, or one may be of type 
\tt{T} and the other of \tt{complex<T>}.  Whenever \tt{v} is an lvalue,
if may be either a \tt{Vector} or a \tt{VectorView}.  Otherwise it can
be a \tt{Vector}, either kind of view, or even a more complicated
expression that evaluates to a \tt{Vector}.

Also, I use the notation \tt{[+-]} to mean either \tt{+} or \tt{-}, since
the syntax is generally the same for these operators.
Likewise, I use \tt{[*/]} when their syntax is equivalent.

\begin{itemize}

\item
\begin{tmvcode}
v [*/]= x;
\end{tmvcode}
Scale the \tt{Vector v} by the scalar value \tt{x}.

\item
\begin{tmvcode}
v2 = -v1;
v2 = x * v1;
v2 = v1 [*/] x;
\end{tmvcode}
Assign a multiple of one \tt{Vector} to another \tt{Vector}.  It is permissible for both vectors to be the same thing (or aliases to the same memory), in which case the \tt{Vector} will be modified in place.

\item
\begin{tmvcode}
v2 [+-]= v1;
v2 [+-]= -v1;
v2 [+-]= x * v1;
v2 [+-]= v1 [*/] x;
\end{tmvcode}
Add one \tt{Vector} (or some multiple of it) to another \tt{Vector}.

\item
\begin{tmvcode}
v3 = v1 [+-] v2;
v3 = x1 * v1 [+-] x2 * v2;
\end{tmvcode}
Assign a sum or difference of two \tt{Vectors} (or scalings thereof) to a third \tt{Vector}.

\item
\begin{tmvcode}
x = v1 * v2;
\end{tmvcode}
Calculate the inner product of two vectors, which is a scalar.  That is, the product
is a row vector times a column vector.  
\index{Vector!Arithmetic!inner product}
This is the only case (so far)
where the specific row or column orientation of a vector matters.  For the others
listed above, the left side and the right side are implied to be of the same orientation, but
that orientation is otherwise arbitrary.
Later, when we get to a matrix times a vector, the orientation 
of the vector will be inferred from context.

\end{itemize}

\subsubsection{Element-by-element product}
\index{Vector!Arithmetic!element by element product}
\label{VectorElementProd}

In addition to the inner product, there are two other kinds of vector products.  The outer product will be discussed in \S\ref{outerproduct} in the section on matrices.

There is also a third kind of product that TMV implements, namely an element-by-element product.  This isn't a product that has a normal arithmetic operator associated with it, but it is occasionally useful when you want to multiply each element in a vector by the corresponding element in another vector: $v(i) = v(i) \cdot w(i)$.  In TMV, this calculation would be written:
\begin{tmvcode}
v = ElemProd(v,w);
\end{tmvcode}

The \tt{ElemProd} function returns a composite object that can be used as part of more complicated arithmetic statements.  e.g.
\begin{tmvcode}
v += 5*ElemProd(w,v) - 6*w;
\end{tmvcode}

This is getting slightly ahead of ourselves, but it is worth noting at this point that the element-by-element product for vectors is equivalent to calculations using diagonal matrices.  A diagonal matrix times a vector does an element-by-element multiplication.  So the above expressions could also be written:
\begin{tmvcode}
v *= DiagMatrixViewOf(w);
v += 5*DiagMatrixViewOf(w)*v - 6*w;
\end{tmvcode}
respectively.  Depending on you preference and the meanings of your vectors,
these statements may or may not be clearer as to what you are doing.

\subsubsection{Delayed evaluation}

Each of the above arithmetic operations use delayed evaluation so that the sum or product is not calculated
until the storage is known.  The equations can even be a bit more complicated without 
requiring a temporary.  Here are some equations that do not require a temporary 
\tt{Vector} for the calculation:

\begin{tmvcode}
v2 = -(x1*v1 + x2*v2);
v2 += x1*(x2*(-v1));
v2 -= x1*(v1/=x2);
\end{tmvcode}

TMV does this by creating composite objects that merely keep track of the
arithmetic operation that is to be done, and then calls a function to do
the calculations when that object is assigned to a \tt{Vector} or
\tt{VectorView}.
If you try to use one of these composite objects in a way that TMV
doesn't know how to deal with directly (e.g. in a more compilicated 
arithmetic expression), it will instantiate a temporary
\tt{Vector} to store the result, and then use that in the next calculation.
Usually, this is the appropriate behavior, but in some cases, it might
be a bit inefficient, so it might be better to break up the calculation 
into smaller pieces.  For example,
\begin{tmvcode}
v1 += x*(v1+v2+v3) + (x*v3-v4);
\end{tmvcode}
will produce the correct answer; however, it will use several temporaries.
If you want to avoid the temporaries, you would want to break up the
calculation into
\begin{tmvcode}
v1 *= x+1;
v1 += x*v2;
v1 += 2*x*v3;
v1 -= v4;
\end{tmvcode}

The limit to how complicated the right hand side can be without using a 
temporary is set by the 
functions that the code eventually calls to perform the calculation, 
but generally speaking, you can assume that scalings will always be
delayed, and other than that you can have a single operator acting on 
two \tt{Vector}s.

\subsection{I/O}
\index{Vector!I/O}
\label{Vector_IO}

The simplest output syntax is the usual:
\begin{tmvcode}
os << v;
\end{tmvcode}
where \tt{os} is any \tt{std::ostream}.
The output format is:
\begin{tmvcode}
n ( v(0)  v(1)  v(2)  ...  v(3) )
\end{tmvcode}
where \tt{n} is the length of the \tt{Vector}.

The same format can be read back using:
\begin{tmvcode}
tmv::Vector<T> v;
is >> v;
\end{tmvcode}
The \tt{Vector v} is automatically resized to the correct size if necessary based in the size given in the input stream.  This is one place where the default constructor (which creates a zero-sized vector) can be useful.
\index{Exceptions!ReadError}

Often, it is convenient to output only those values that aren't very small. 
This can be done using an equivalent of a stream manipulator:
\begin{tmvcode}
os << tmv::ThreshIO(thresh) << v;
\end{tmvcode}
\index{IOStyle!ThreshIO}
which writes as 0 any value smaller (in absolute value) than \tt{thresh}.  
For real \tt{v} it is equivalent to
\begin{tmvcode}
os << tmv::Vector<T>(v).clip(thresh);
\end{tmvcode}
\index{Vector!clip}
but without requiring the temporary \tt{Vector}.  For complex \tt{v} it is slightly different, since it separately tests each component of the complex number.  So if \tt{thresh} is \tt{1.e-8}, the complex value \tt{(8,7.5624e-12)} would be writtend \tt{(8,0)}.

There is also a compact I/O format which is mediated by the manipulator
\tt{tmv::CompactIO()}.  For \tt{Vector} it doesn't make much difference, basically
just skipping the parentheses and used a little less space between elements:
\begin{tmvcode}
os << tmv::CompactIO() << v;
\end{tmvcode}
\index{IOStyle!CompactIO}
would produce the output:
\begin{tmvcode}
V n v(0) v(1) v(2) ... v(3)
\end{tmvcode}
The compact I/O is more useful for some of the special matrix varieties where it can skip 
some zeros that would otherwise be printed and output extra information that might be required
to resize the matrix correctly on input.

See \S\ref{IOStyle} for more information about specifying custom I/O styles, including
features like using brackets instead of parentheses, or putting commas between elements,
or specifying an output precision.  

\subsection{Vector Iterators}
\index{Vector!Iterators}
\label{VectorIterators}

We mentioned that the iterators through a \tt{Vector} are:
\begin{tmvcode}
Vector<T>::iterator
Vector<T>::const_iterator
Vector<T>::reverse_iterator
Vector<T>::const_reverse_iterator
\end{tmvcode}
just like for standard library containers.  Sometimes it can be useful to use the underlying iterator types that TMV uses rather than merely the above typedefs.  The specific types to which these
typedefs refer are:
\begin{tmvcode}
tmv::VIt<T,1,tmv::NonConj>
tmv::CVIt<T,1,tmv::NonConj>
tmv::VIt<T,-1,tmv::NonConj>
tmv::CVIt<T,-1,tmv::NonConj>
\end{tmvcode}
\label{VIt}
\label{CVIt}
respectively.  They all satisfy the requirements of a STL random-access iterator.
\tt{VIt} is a mutable iterator, and \tt{CVIt} is a const iterator.

The second template parameter is the step size between successive elements, if known at compile time.  If the step size is not known at compile time, you can use the special value \tt{tmv::Unknown}, and TMV will get the correct value at run time.  

The third template parameter must be either \tt{tmv::NonConj} or \tt{tmv::Conj} and indicates whether the values being iterated over are the actual values in memory or their conjugates, respectively.

These types can be worth using explicitly if you want to optimize code that uses iterators of \tt{VectorView}s.
This is because their iterators always use \tt{tmv::Unknown} as the step parameter.  For complex \tt{VectorView}s, it is even worse, since the possible conjugation is also a run-time variable.  These use a different type that allows for the variable conjugation possibility:
\begin{tmvcode}
tmv::VarConjIter<T>
tmv::CVarConjIter<T>
\end{tmvcode}
\label{VarConjIter}
\label{CVarConjIter}

If you know that you are dealing with a complex view that is not conjugated, you can 
convert your iterator into one of the above \tt{VIt} or \tt{CVIt} types, which will be 
faster, since they won't check the conjugation bit each time. 
Likewise, if you
know that it {\em is} conjugated, then you can use \tt{tmv::Conj} for the 
third template parameter above.

Also, if you know the step size between elements at compile time, converting to 
an iterator with that step size will iterate faster, especially if that step size is known to be 1.

All of these conversions can be done seamlessly through assignments.  E.g.
\begin{tmvcode}
if (v.step() == 1)
    for(VIt<float,1,NonConj> it = v.begin(); it != v.end(); ++it)
        (*it) = sqrt(*it);
else 
    for(VIt<float,Unknown,NonConj> it = v.begin(); it != v.end(); ++it)
        (*it) = sqrt(*it);
\end{tmvcode}

\subsection{Small vectors}
\index{SmallVector}
\label{SmallVector}

For small vectors, it is often the case that you know the size of the vector
at compile time.  Thus, we provide a class \tt{SmallVector} that takes an
additional template argument, \tt{N}, the size of the vector.

All the \tt{SmallVector} routines are included by:
\begin{tmvcode}
#include "TMV_Small.h"
\end{tmvcode}
\index{TMV\_Small.h}
\tt{SmallVector} does not inherit from the regular \tt{Vector} class, but it has 
essentially all the same methods, functions, and arithmetic operators. 

\subsubsection{Constructors}
\index{SmallVector!Constructors}
\label{SmallVector_Constructors}

The template argument \tt{N} below is an integer and
represent the size of the vector.
The final template argument 
 \tt{A} specifies the known attributes.  It may be either \tt{tmv::CStyle} or
\tt{tmv::FortranStyle} and has the same meanings as 
for a regular \tt{Vector}. The default is \tt{CStyle} if it is omitted.

\begin{itemize}
\item 
\begin{tmvcode}
tmv::SmallVector<T,N,A> v()
\end{tmvcode}
Makes a \tt{SmallVector} of size \tt{N}
with {\em uninitialized} values.

\item
\begin{tmvcode}
tmv::SmallVector<T,N,A> v(T x)
\end{tmvcode}
Makes a \tt{SmallVector} with all values equal to \tt{x}.

\item 
\begin{tmvcode}
tmv::SmallVector<T,N,A> v1(const Vector<T>& v2)
\end{tmvcode}
Makes a \tt{SmallVector} from a regular \tt{Vector}.

\item
\begin{tmvcode}
tmv::SmallVector<T,N,A> v1(const SmallVector<T2,N,A2>& v2)
v1 = v2
\end{tmvcode}
Copy the \tt{SmallVector v2}, which may be of any type \tt{T2} so long
as values of type \tt{T2} are convertible into type \tt{T}.
The assignment operator has the same flexibility.

\item
\begin{tmvcode}
v << v0 , v1 , v2 , v3 ...
v << v0 << v1 << v2 << v3 ...
\end{tmvcode}
Initialize the \tt{SmallVector v} with a list of values.
\index{SmallVector!List initialization}

\end{itemize}

\subsubsection{Access}
\index{SmallVector!Access methods}
\label{SmallVector_Access}

The basic access methods are the same as for a regular \tt{Vector}.
(See \ref{Vector_Access}.)
However, since the size is known to the compiler, the inline calculation is able
to be a lot faster, often reducing to a trivial memory access.

The various view methods, like \tt{reverse} or \tt{subVector},
do not return a \tt{SmallVector}, so operations 
with the returned views will not necessarily be done inline.
However, you can copy the view back to a ``\tt{Small}'' object, which will be done 
inline, so that should be fast.

Also, if the code can determine the size from other objects in the calculation, then
it will be done inline.  e.g. if \tt{v} is a \tt{SmallVector}, then 
\tt{v2 = v + v.reverse()} will be done inline, since the first \tt{v} does have 
the compile-time knowledge about the size of the calculation.

\subsubsection{Functions}
\index{SmallVector!Functions of}
\label{SmallVector_Functions}

\tt{SmallVector} has exactly the same
function methods as the regular \tt{Vector}.  
(See \ref{Vector_Functions}.)
Likewise, the syntax of the
arithmetic is identical.  There are only a few methods that 
are not done inline.  
First, reading \tt{SmallVector} from a file 
uses the regular
\tt{Vector} I/O methods.  
Also, the \tt{sort} command for a \tt{SmallVector} just uses the
regular \tt{Vector} version.

